<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Boxplot Aggregation | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="search-aggregations-metrics.html" title="Metrics Aggregations">
<link rel="prev" href="search-aggregations-metrics-weight-avg-aggregation.html" title="Weighted Avg Aggregation">
<link rel="next" href="search-aggregations-metrics-cardinality-aggregation.html" title="Cardinality Aggregation">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations.html">Aggregations</a></span>
»
<span class="breadcrumb-link"><a href="search-aggregations-metrics.html">Metrics Aggregations</a></span>
»
<span class="breadcrumb-node">Boxplot Aggregation</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-aggregations-metrics-weight-avg-aggregation.html">« Weighted Avg Aggregation</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-cardinality-aggregation.html">Cardinality Aggregation »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-aggregations-metrics-boxplot-aggregation"></a>Boxplot Aggregation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p>A <code class="literal">boxplot</code> metrics aggregation that computes boxplot of numeric values extracted from the aggregated documents.
These values can be generated by a provided script or extracted from specific numeric or
<a class="xref" href="histogram.html" title="Histogram datatype">histogram fields</a> in the documents.</p>
<p>The <code class="literal">boxplot</code> aggregation returns essential information for making a <a href="https://en.wikipedia.org/wiki/Box_plot" class="ulink" target="_top">box plot</a>: minimum, maximum
median, first quartile (25th percentile)  and third quartile (75th percentile) values.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_syntax"></a>Syntax<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>A <code class="literal">boxplot</code> aggregation looks like this in isolation:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
    "boxplot": {
        "field": "load_time"
    }
}</pre>
</div>
<p>Let’s look at a boxplot representing load time:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_boxplot" : {
            "boxplot" : {
                "field" : "load_time" <a id="CO180-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/329.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO180-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The field <code class="literal">load_time</code> must be a numeric field</p>
</td>
</tr>
</table>
</div>
<p>The response will look like this:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    ...

   "aggregations": {
      "load_time_boxplot": {
         "min": 0.0,
         "max": 990.0,
         "q1": 165.0,
         "q2": 445.0,
         "q3": 725.0
      }
   }
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_script_3"></a>Script<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The boxplot metric supports scripting.  For example, if our load times
are in milliseconds but we want values calculated in seconds, we could use
a script to convert them on-the-fly:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_boxplot" : {
            "boxplot" : {
                "script" : {
                    "lang": "painless",
                    "source": "doc['load_time'].value / params.timeUnit", <a id="CO181-1"></a><i class="conum" data-value="1"></i>
                    "params" : {
                        "timeUnit" : 1000   <a id="CO181-2"></a><i class="conum" data-value="2"></i>
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/330.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO181-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">field</code> parameter is replaced with a <code class="literal">script</code> parameter, which uses the
script to generate values which percentiles are calculated on</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO181-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Scripting supports parameterized input just like any other script</p>
</td>
</tr>
</table>
</div>
<p>This will interpret the <code class="literal">script</code> parameter as an <code class="literal">inline</code> script with the <code class="literal">painless</code> script language and no script parameters. To use a
stored script use the following syntax:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_boxplot" : {
            "boxplot" : {
                "script" : {
                    "id": "my_script",
                    "params": {
                        "field": "load_time"
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/331.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-aggregations-metrics-boxplot-aggregation-approximation"></a>Boxplot values are (usually) approximate<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The algorithm used by the <code class="literal">boxplot</code> metric is called TDigest (introduced by
Ted Dunning in
<a href="https://github.com/tdunning/t-digest/blob/master/docs/t-digest-paper/histo.pdf" class="ulink" target="_top">Computing Accurate Quantiles using T-Digests</a>).</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>Boxplot as other percentile aggregations are also
<a href="https://en.wikipedia.org/wiki/Nondeterministic_algorithm" class="ulink" target="_top">non-deterministic</a>.
This means you can get slightly different results using the same data.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-aggregations-metrics-boxplot-aggregation-compression"></a>Compression<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Approximate algorithms must balance memory utilization with estimation accuracy.
This balance can be controlled using a <code class="literal">compression</code> parameter:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "load_time_boxplot" : {
            "boxplot" : {
                "field" : "load_time",
                "compression" : 200 <a id="CO182-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/332.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO182-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Compression controls memory usage and approximation error</p>
</td>
</tr>
</table>
</div>
<p>The TDigest algorithm uses a number of "nodes" to approximate percentiles — the
more nodes available, the higher the accuracy (and large memory footprint) proportional
to the volume of data.  The <code class="literal">compression</code> parameter limits the maximum number of
nodes to <code class="literal">20 * compression</code>.</p>
<p>Therefore, by increasing the compression value, you can increase the accuracy of
your percentiles at the cost of more memory.  Larger compression values also
make the algorithm slower since the underlying tree data structure grows in size,
resulting in more expensive operations.  The default compression value is
<code class="literal">100</code>.</p>
<p>A "node" uses roughly 32 bytes of memory, so under worst-case scenarios (large amount
of data which arrives sorted and in-order) the default settings will produce a
TDigest roughly 64KB in size.  In practice data tends to be more random and
the TDigest will use less memory.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_missing_value_2"></a>Missing value<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The <code class="literal">missing</code> parameter defines how documents that are missing a value should be treated.
By default they will be ignored but it is also possible to treat them as if they
had a value.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET latency/_search
{
    "size": 0,
    "aggs" : {
        "grade_boxplot" : {
            "boxplot" : {
                "field" : "grade",
                "missing": 10 <a id="CO183-1"></a><i class="conum" data-value="1"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/333.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO183-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Documents without a value in the <code class="literal">grade</code> field will fall into the same bucket as documents that have the value <code class="literal">10</code>.</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-aggregations-metrics-weight-avg-aggregation.html">« Weighted Avg Aggregation</a>
</span>
<span class="next">
<a href="search-aggregations-metrics-cardinality-aggregation.html">Cardinality Aggregation »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
